Introduction

This document details the Atlas of Living Australia style guide for creating html files from R Markdown

Style Template

A test of a chunk

library(kableExtra)
library(tidyverse)

# a table
head(mtcars, n=5) %>%
  kbl() %>%
  kable_styling()
mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1
Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2


Getting started

Use ALA Template

Create a new R Markdown document by selecting File –> New File –> R Markdown

In the left window menu, select New Template. Then select the ALA Template

Add your information

  1. In the top 3 lines, add your document title, your name and the date. Leave the remainder of the .yaml options unchanged.

  2. Next, scroll down to the code chunk named upper right bio. This code chunk adds your image and links to your personal websites

    • Save your preferred picture as “picture.jpg” in the current directory
    • Add the urls you wish to link to for the correct websites & icons
`{r upper right bio, echo = FALSE}
htmltools::withTags(
  div(id = "pictureposition",
      
      
# Save your own picture as "picture.jpg" to local directory
      img(src = knitr::image_uri("picture.jpg"),
          class = "clipped", 
          style = 'height:80px'),
      
# Add links to personal accounts below and uncomment
      div(id = "linkposition",
          # a(href="your-url", # twitter
          #   class="fab fa-twitter",
          #   style = "text-align:center"),
          # a(href="your-url", # github
          #   class="fab fa-github",
          #   style = "text-align:center")
          # a(href="your-url", # linkedIn
          #   class="fab fa-linkedin",
          #   style = "text-align:center")
          )))
`


Knit to HTML

Click the Knit button in the upper menu (below file tabs, above script) to create an HTML file. A preview of your knitted HTML document can be viewed in the right pane. Code must run successfully from start to finish for a file to be Knit.

In the R Studio viewer pane, click the “Show in New Window ” button to view the page in your browser.


Push to Github


Make understandable code

Code chunk size

Good writing involves logically structuring sentences of varying lengths to build an argument. In the same way, chunks can be used to structure lines of code to build an analysis or plot.

Users should be able to follow each transformation that is made to your data. Code chunks should be brief. They should also offer notes or visual output that provides context to any transformations or outputs.

There is no single correct code chunk size - you must use your best judgement. If it seems that the result of one or several lines of code is unclear a potential reader, you may need to split the code chunks to make the results easier to follow.

Brief summaries

For others to understand what your code does and why you made the choices you did, it is helpful to include brief summaries or your logic or what each line of your code does. It is also good to provide a brief interpretation of model output

Using code chunks

See the R markdown documentation to view chunk options.

Examples

It is essential that readers can identify where every file comes from (little is more frustrating than wondering where a necessary data file is located). Code used to load or extract data (from galah, for example) should be clearly identified.

It is possible to show code that takes a long time (which often happens when loading large datasets) without running it.

Add eval = FALSE to the chunk header to display the code but prevent the chunk from running:

 ```{r, eval = FALSE}`
 
 ala_counts(group_by = "phylum")

You can then load a local file with saved output without showing the code.

Add echo = FALSE to your chunk header to run the code but prevent the chunk from displaying:

 ```{r, echo = FALSE}`
 
 data <- readRDS(file = "local_file.rds")
 

By Dax Kellie

Atlas of Living Australia